home *** CD-ROM | disk | FTP | other *** search
/ Power Programmierung 2 / Power-Programmierung CD 2 (Tewi)(1994).iso / gnu / gnulib / sipp / doc / sipp.1 < prev    next >
Encoding:
GNU Info File  |  1994-02-16  |  48.5 KB  |  1,189 lines
  1. This is Info file sipp, produced by Makeinfo-1.55 from the input file
  2. sipp.tex.
  3.  
  4.    Copyright (C) 1992 Jonas Yngvesson, Inge Wallin
  5.  
  6. 
  7. File: sipp,  Node: Top,  Prev: (dir),  Up: (dir)
  8.  
  9.    This Info manual describes SIPP, a 3D rendering library.  SIPP can
  10. be used for creating 3-dimensional scenes and rendering them using a
  11. scan-line z-buffer algorithm. A scene is built up of objects which can
  12. be transformed with rotation, translation and scaling. The objects form
  13. hierarchies where each object can have arbitrarily many subobjects and
  14. subsurfaces. A surface is a number of connected polygons which are
  15. rendered with either Phong, Gouraud or flat shading.  An image can also
  16. be rendered as a line drawing of the polygon edges without any shading
  17. at all.
  18.  
  19. * Menu:
  20.  
  21. * License information::  Information about terms for copying SIPP.
  22. * What is SIPP?::        An overview of SIPP.
  23. * Installation::         How to install SIPP on your system.
  24. * Getting started::      Tutorial introduction.
  25. * Basic concepts::       Some basic concepts used in SIPP.
  26. * Initializations::      Necessary and optional initializations.
  27. * Creating objects::     How to build and install objects.
  28. * Transformations::      Transformations of objects.
  29. * Lights::               How to lit the stage.
  30. * Shadows::              How to create good looking shadows.
  31. * Viewpoint and cameras::Specifying viewing parameters.
  32. * Rendering::            The different rendering variants available.
  33. * Shaders::              Issues regarding shading functions for SIPP
  34. * Object primitives::    Object primitives included in the library.
  35. * Future enhancements::  Possible future enhancements of SIPP.
  36. * Reporting bugs::       Where do you report a bug you have found?
  37.  
  38. * Concept index::        Index over important concepts in SIPP.
  39. * Function index::       Index over the available functions in SIPP.
  40.  
  41. 
  42. File: sipp,  Node: License information,  Next: What is SIPP?,  Prev: Top,  Up: Top
  43.  
  44. GNU GENERAL PUBLIC LICENSE
  45. **************************
  46.  
  47.                        Version 1, February 1989
  48.  
  49.      Copyright (C) 1989 Free Software Foundation, Inc.
  50.      675 Mass Ave, Cambridge, MA 02139, USA
  51.      
  52.      Everyone is permitted to copy and distribute verbatim copies
  53.      of this license document, but changing it is not allowed.
  54.  
  55. Preamble
  56. ========
  57.  
  58.    The license agreements of most software companies try to keep users
  59. at the mercy of those companies.  By contrast, our General Public
  60. License is intended to guarantee your freedom to share and change free
  61. software--to make sure the software is free for all its users.  The
  62. General Public License applies to the Free Software Foundation's
  63. software and to any other program whose authors commit to using it.
  64. You can use it for your programs, too.
  65.  
  66.    When we speak of free software, we are referring to freedom, not
  67. price.  Specifically, the General Public License is designed to make
  68. sure that you have the freedom to give away or sell copies of free
  69. software, that you receive source code or can get it if you want it,
  70. that you can change the software or use pieces of it in new free
  71. programs; and that you know you can do these things.
  72.  
  73.    To protect your rights, we need to make restrictions that forbid
  74. anyone to deny you these rights or to ask you to surrender the rights.
  75. These restrictions translate to certain responsibilities for you if you
  76. distribute copies of the software, or if you modify it.
  77.  
  78.    For example, if you distribute copies of a such a program, whether
  79. gratis or for a fee, you must give the recipients all the rights that
  80. you have.  You must make sure that they, too, receive or can get the
  81. source code.  And you must tell them their rights.
  82.  
  83.    We protect your rights with two steps: (1) copyright the software,
  84. and (2) offer you this license which gives you legal permission to copy,
  85. distribute and/or modify the software.
  86.  
  87.    Also, for each author's protection and ours, we want to make certain
  88. that everyone understands that there is no warranty for this free
  89. software.  If the software is modified by someone else and passed on, we
  90. want its recipients to know that what they have is not the original, so
  91. that any problems introduced by others will not reflect on the original
  92. authors' reputations.
  93.  
  94.    The precise terms and conditions for copying, distribution and
  95. modification follow.
  96.  
  97.                          TERMS AND CONDITIONS
  98.  
  99.   1. This License Agreement applies to any program or other work which
  100.      contains a notice placed by the copyright holder saying it may be
  101.      distributed under the terms of this General Public License.  The
  102.      "Program", below, refers to any such program or work, and a "work
  103.      based on the Program" means either the Program or any work
  104.      containing the Program or a portion of it, either verbatim or with
  105.      modifications.  Each licensee is addressed as "you".
  106.  
  107.   2. You may copy and distribute verbatim copies of the Program's source
  108.      code as you receive it, in any medium, provided that you
  109.      conspicuously and appropriately publish on each copy an
  110.      appropriate copyright notice and disclaimer of warranty; keep
  111.      intact all the notices that refer to this General Public License
  112.      and to the absence of any warranty; and give any other recipients
  113.      of the Program a copy of this General Public License along with
  114.      the Program.  You may charge a fee for the physical act of
  115.      transferring a copy.
  116.  
  117.   3. You may modify your copy or copies of the Program or any portion of
  118.      it, and copy and distribute such modifications under the terms of
  119.      Paragraph 1 above, provided that you also do the following:
  120.  
  121.         * cause the modified files to carry prominent notices stating
  122.           that you changed the files and the date of any change; and
  123.  
  124.         * cause the whole of any work that you distribute or publish,
  125.           that in whole or in part contains the Program or any part
  126.           thereof, either with or without modifications, to be licensed
  127.           at no charge to all third parties under the terms of this
  128.           General Public License (except that you may choose to grant
  129.           warranty protection to some or all third parties, at your
  130.           option).
  131.  
  132.         * If the modified program normally reads commands interactively
  133.           when run, you must cause it, when started running for such
  134.           interactive use in the simplest and most usual way, to print
  135.           or display an announcement including an appropriate copyright
  136.           notice and a notice that there is no warranty (or else,
  137.           saying that you provide a warranty) and that users may
  138.           redistribute the program under these conditions, and telling
  139.           the user how to view a copy of this General Public License.
  140.  
  141.         * You may charge a fee for the physical act of transferring a
  142.           copy, and you may at your option offer warranty protection in
  143.           exchange for a fee.
  144.  
  145.      Mere aggregation of another independent work with the Program (or
  146.      its derivative) on a volume of a storage or distribution medium
  147.      does not bring the other work under the scope of these terms.
  148.  
  149.   4. You may copy and distribute the Program (or a portion or
  150.      derivative of it, under Paragraph 2) in object code or executable
  151.      form under the terms of Paragraphs 1 and 2 above provided that you
  152.      also do one of the following:
  153.  
  154.         * accompany it with the complete corresponding machine-readable
  155.           source code, which must be distributed under the terms of
  156.           Paragraphs 1 and 2 above; or,
  157.  
  158.         * accompany it with a written offer, valid for at least three
  159.           years, to give any third party free (except for a nominal
  160.           charge for the cost of distribution) a complete
  161.           machine-readable copy of the corresponding source code, to be
  162.           distributed under the terms of Paragraphs 1 and 2 above; or,
  163.  
  164.         * accompany it with the information you received as to where the
  165.           corresponding source code may be obtained.  (This alternative
  166.           is allowed only for noncommercial distribution and only if you
  167.           received the program in object code or executable form alone.)
  168.  
  169.      Source code for a work means the preferred form of the work for
  170.      making modifications to it.  For an executable file, complete
  171.      source code means all the source code for all modules it contains;
  172.      but, as a special exception, it need not include source code for
  173.      modules which are standard libraries that accompany the operating
  174.      system on which the executable file runs, or for standard header
  175.      files or definitions files that accompany that operating system.
  176.  
  177.   5. You may not copy, modify, sublicense, distribute or transfer the
  178.      Program except as expressly provided under this General Public
  179.      License.  Any attempt otherwise to copy, modify, sublicense,
  180.      distribute or transfer the Program is void, and will automatically
  181.      terminate your rights to use the Program under this License.
  182.      However, parties who have received copies, or rights to use
  183.      copies, from you under this General Public License will not have
  184.      their licenses terminated so long as such parties remain in full
  185.      compliance.
  186.  
  187.   6. By copying, distributing or modifying the Program (or any work
  188.      based on the Program) you indicate your acceptance of this license
  189.      to do so, and all its terms and conditions.
  190.  
  191.   7. Each time you redistribute the Program (or any work based on the
  192.      Program), the recipient automatically receives a license from the
  193.      original licensor to copy, distribute or modify the Program
  194.      subject to these terms and conditions.  You may not impose any
  195.      further restrictions on the recipients' exercise of the rights
  196.      granted herein.
  197.  
  198.   8. The Free Software Foundation may publish revised and/or new
  199.      versions of the General Public License from time to time.  Such
  200.      new versions will be similar in spirit to the present version, but
  201.      may differ in detail to address new problems or concerns.
  202.  
  203.      Each version is given a distinguishing version number.  If the
  204.      Program specifies a version number of the license which applies to
  205.      it and "any later version", you have the option of following the
  206.      terms and conditions either of that version or of any later
  207.      version published by the Free Software Foundation.  If the Program
  208.      does not specify a version number of the license, you may choose
  209.      any version ever published by the Free Software Foundation.
  210.  
  211.   9. If you wish to incorporate parts of the Program into other free
  212.      programs whose distribution conditions are different, write to the
  213.      author to ask for permission.  For software which is copyrighted
  214.      by the Free Software Foundation, write to the Free Software
  215.      Foundation; we sometimes make exceptions for this.  Our decision
  216.      will be guided by the two goals of preserving the free status of
  217.      all derivatives of our free software and of promoting the sharing
  218.      and reuse of software generally.
  219.  
  220.                                 NO WARRANTY
  221.  
  222.  10. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
  223.      WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
  224.      LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  225.      HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
  226.      WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
  227.      NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  228.      FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
  229.      QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
  230.      PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  231.      SERVICING, REPAIR OR CORRECTION.
  232.  
  233.  11. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  234.      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
  235.      MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
  236.      LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
  237.      INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
  238.      INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
  239.      DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
  240.      OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
  241.      OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
  242.      ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  243.  
  244.                       END OF TERMS AND CONDITIONS
  245.  
  246. Applying These Terms to Your New Programs
  247. =========================================
  248.  
  249.    If you develop a new program, and you want it to be of the greatest
  250. possible use to humanity, the best way to achieve this is to make it
  251. free software which everyone can redistribute and change under these
  252. terms.
  253.  
  254.    To do so, attach the following notices to the program.  It is safest
  255. to attach them to the start of each source file to most effectively
  256. convey the exclusion of warranty; and each file should have at least the
  257. "copyright" line and a pointer to where the full notice is found.
  258.  
  259.      ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
  260.      Copyright (C) 19YY  NAME OF AUTHOR
  261.      
  262.      This program is free software; you can redistribute it and/or modify
  263.      it under the terms of the GNU General Public License as published by
  264.      the Free Software Foundation; either version 1, or (at your option)
  265.      any later version.
  266.      
  267.      This program is distributed in the hope that it will be useful,
  268.      but WITHOUT ANY WARRANTY; without even the implied warranty of
  269.      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  270.      GNU General Public License for more details.
  271.      
  272.      You should have received a copy of the GNU General Public License
  273.      along with this program; if not, write to the Free Software
  274.      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  275.  
  276.    Also add information on how to contact you by electronic and paper
  277. mail.
  278.  
  279.    If the program is interactive, make it output a short notice like
  280. this when it starts in an interactive mode:
  281.  
  282.      Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
  283.      Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
  284.      This is free software, and you are welcome to redistribute it
  285.      under certain conditions; type `show c' for details.
  286.  
  287.    The hypothetical commands `show w' and `show c' should show the
  288. appropriate parts of the General Public License.  Of course, the
  289. commands you use may be called something other than `show w' and `show
  290. c'; they could even be mouse-clicks or menu items--whatever suits your
  291. program.
  292.  
  293.    You should also get your employer (if you work as a programmer) or
  294. your school, if any, to sign a "copyright disclaimer" for the program,
  295. if necessary.  Here a sample; alter the names:
  296.  
  297.      Yoyodyne, Inc., hereby disclaims all copyright interest in the
  298.      program `Gnomovision' (a program to direct compilers to make passes
  299.      at assemblers) written by James Hacker.
  300.      
  301.      SIGNATURE OF TY COON, 1 April 1989
  302.      Ty Coon, President of Vice
  303.  
  304.    That's all there is to it!
  305.  
  306. 
  307. File: sipp,  Node: What is SIPP?,  Next: Installation,  Prev: License information,  Up: Top
  308.  
  309. What is SIPP?
  310. *************
  311.  
  312.    SIPP is a library for creating 3-dimensional scenes and rendering
  313. them using a scan-line z-buffer algorithm. A scene is built up of
  314. objects which can be transformed with rotation, translation and
  315. scaling. The objects form hierarchies where each object can have
  316. arbitrarily many subobjects and subsurfaces. A surface is a number of
  317. connected polygons which are rendered with either Phong, Gouraud or
  318. flat shading.  An image can also be rendered as a line drawing of the
  319. polygon edges without any shading at all.
  320.  
  321.    The library also provides 3-dimensional texture mapping with
  322. automatic interpolation of texture coordinates. Simple anti-aliasing
  323. can be performed through oversampling. The scene can be illuminated by
  324. an arbitrary number of lightsources. These lightsources can be of three
  325. basic types: directional, point or spotlight. Light from spotlights can
  326. cast shadows.
  327.  
  328.    It is possible to create several virtual cameras, and then specify
  329. one of them to use when rendering the image.
  330.  
  331.    A major feature in SIPP is the ability for a user to provide his own
  332. shading function for a surface. This makes it easy to experiment with
  333. various shading models and to do special effects. A basic shading
  334. algorithm is provided with the library, and also a package of other,
  335. more special shaders.
  336.  
  337.    Images can be rendered directly onto a file in the Portable Pixmap
  338. format (ppm) or, for line images, Portable Bitmap, (pbm) or, with a
  339. function defined by the user, into anything that it is capable of
  340. plotting a pixel (or drawing a line), e.g. a window in a window system
  341. or even a plotter file.
  342.  
  343.    The object creation functions in SIPP are on a rather low level so to
  344. make it easier to build scenes, a set of object primitives, like sphere,
  345. cylinder, prism etc., is included.
  346.  
  347. * Menu:
  348.  
  349. * Authors::             Authors of SIPP.
  350. * Archives::            Where can I get a copy of SIPP?
  351.  
  352. 
  353. File: sipp,  Node: Authors,  Next: Archives,  Up: What is SIPP?
  354.  
  355. Authors of SIPP
  356. ===============
  357.  
  358.    The following persons have written or contributed to SIPP.
  359.  
  360.    * Jonas Yngvesson wrote most of the otherwise unattributed functions
  361.      in SIPP as well as most of the documentation.
  362.  
  363.    * Inge Wallin wrote the geometric functions, some object primitives,
  364.      pixmap functions, several demonstration programs and the rest of
  365.      the documentation.
  366.  
  367.    * David Jones provided the code for the prism and cone primitives.
  368.  
  369.    * Jon Buller wrote the noise and Dnoise functions (not specifically
  370.      for SIPP though, they were posted on the net).
  371.  
  372.    * Several other people have aided the development by reporting bugs,
  373.      suggested enhancements, etc. etc. I will not mention any names,
  374.      you know who you are.
  375.  
  376. 
  377. File: sipp,  Node: Archives,  Prev: Authors,  Up: What is SIPP?
  378.  
  379. Where can I get SIPP?
  380. =====================
  381.  
  382.    There will probably be a number of sites archiving SIPP.  Currently
  383. the latest release can always be fetched via anonymous ftp from
  384. `isy.liu.se', (IP no. 130.236.1.3) in the directory `pub/sipp'.
  385.  
  386.    Two older versions (2.0 and 2.1) have been posted to
  387. comp.sources.misc.  They are in Volume 16 and Volume 21 respectively
  388. and should be on any site that archives that group.
  389.  
  390. 
  391. File: sipp,  Node: Installation,  Next: Getting started,  Prev: What is SIPP?,  Up: Top
  392.  
  393. Installation
  394. ************
  395.  
  396.    This section describes the installation of the SIPP rendering
  397. library.  You should install not only the library itself, but also the
  398. on-line documentation so that your users will know how to use it.  You
  399. can create typeset documentation from the file `sipp.texinfo' as well
  400. as an on-line Info file.  The following steps are also described in the
  401. file `INSTALL' in the directory `sipp-3.0'.
  402.  
  403. * Menu:
  404.  
  405. * Library installation::        How to install SIPP on your system.
  406. * Info manual installation::    How to install the Info manual.
  407. * Typeset manual installation:: How to create typeset documentation about SIPP.
  408.  
  409. 
  410. File: sipp,  Node: Library installation,  Next: Info manual installation,  Up: Installation
  411.  
  412. Installation of the SIPP library
  413. ================================
  414.  
  415.    Edit the file `Makefile' to reflect the situation at your site. The
  416. things you might have to change are clearly marked in the beginning of
  417. that file. They are also described below.
  418.  
  419.    * The `NOVOID' definition should be used if the C compiler on your
  420.      system does not understand the type `void'.
  421.  
  422.    * If the C library on your system does not contain the functions
  423.      `memcpy()' or `memset()', or the include file `memory.h' does not
  424.      exist, you should use the `NOMEMCPY' definition.
  425.  
  426.    * If your system does not support the `alloca()' function, the
  427.      `ALLOCA' definition should be used. This will cause SIPP to use the
  428.      portable version of `alloca()' available from the GNU project.
  429.  
  430.    * The definitions of `LIBDIR', `INCLUDEDIR', `MANDIR' and `MANEXT'
  431.      determines where in your file hierarchy SIPP will be installed.
  432.      `LIBDIR' is the directory where the final library file
  433.      (`libsipp.a') will be placed. When a program that uses SIPP is
  434.      linked, this directory should be in the path where the linker
  435.      looks for libraries, either direct or with the aid of the `-L'
  436.      switch.  `INCLUDEDIR' is the directory where the includefiles
  437.      necessary to use SIPP will be placed. When a program that uses
  438.      SIPP is compiled, this directory should be in the path where the
  439.      compiler searches for include files, either direct or with the aid
  440.      of the `-I' switch.  `MANDIR' is the directory in which to place
  441.      the UNIX style `man' page provided with SIPP. `MANEXT' determines
  442.      what extension that manual file will get.
  443.  
  444.    Apart from these SIPP specific definitions, the usual C compiler and
  445. flags to this compiler must of course be set to values suitable on your
  446. system.
  447.  
  448.    The only other item, apart from the `Makefile', is a definition in
  449. the includefile `sipp.h' in the `libsipp' directory. In this file a
  450. macro called `RANDOM()' is defined. If your system does not have the
  451. `drand48()' function, you must change this definition. The macro should
  452. return a random floating point number in the range (-1, 1).
  453.  
  454.    By just typing `make' in the `sipp-3.0' directory, the library and
  455. the demonstration programs will be compiled. The library is not
  456. installed, but only compiled in place.
  457.  
  458.    By typing `make library', the library will be compiled in place but
  459. the demonstration programs will not.
  460.  
  461.    Typing `make demos' will compile the demonstration programs only.
  462. Since the demos require it, however, the library will also be compiled
  463. if it was not done before.
  464.  
  465.    Finally, typing `make install' will compile the library if it was
  466. not done before, and copy that, the include files and the manual pages
  467. to their appropriate places.
  468.  
  469. 
  470. File: sipp,  Node: Info manual installation,  Next: Typeset manual installation,  Prev: Library installation,  Up: Installation
  471.  
  472. Installation of the on-line Info manual.
  473. ========================================
  474.  
  475.   1. Create the Info files `sipp', `sipp-1', `sipp-2' and so on from
  476.      `sipp.texinfo'.  If you have the `makeinfo' program, you can do
  477.      this by running it on `sipp.texinfo'.  Otherwise you can do it
  478.      with emacs by running these steps:
  479.        1. Read `sipp.texinfo' into an emacs buffer.
  480.  
  481.        2. Type ``M-X texinfo-format-buffer''
  482.  
  483.        3. Save the newly created Info file `sipp', `sipp-1', `sipp-2'
  484.           and so on .
  485.  
  486.   2. Move the Info file `sipp', `sipp-1', `sipp-2' and so on to the
  487.      standard Info directory.  Usually this is `/usr/gnu/emacs/info' or
  488.      something similar. (See step 3 above).
  489.  
  490.   3. Edit the file `dir' in the info directory and enter one line to
  491.      contain a pointer to the Info file `sipp'.  The line can, for
  492.      instance, look like this:
  493.  
  494.           * SIPP: (sipp).       3D rendering library.
  495.  
  496.  
  497. 
  498. File: sipp,  Node: Typeset manual installation,  Prev: Info manual installation,  Up: Installation
  499.  
  500. How to make typeset documentation from sipp.texinfo
  501. ===================================================
  502.  
  503.    You can also make a typeset manual from the file `sipp.texinfo'.  To
  504. do this, you must have the TeX text formatting program installed.  Just
  505. follow these steps:
  506.  
  507.   1. If the file `texinfo.tex' is not properly installed in the path
  508.      given by the environment variable TEXINPUTS, get it and put it in
  509.      the same directory as `sipp.texinfo' (the `doc' directory of
  510.      SIPP).  This file contains macros used by the TeX text formatting
  511.      program to produce typeset output from a texinfo file. You can get
  512.      this from, e.g., `prep.ai.mit.edu' in the US or from `isy.liu.se'
  513.      in Europe.
  514.  
  515.   2. Run TeX by typing ``tex sipp.texinfo''.  You might need to do this
  516.      twice to get all cross references correct.  If you have the
  517.      `texindex' program, you can create a sorted index by typing
  518.      ``texindex sipp.cp sipp.fn'' between the two TeX passes.  If you
  519.      don't do this, you still get a typeset manual, but you will not
  520.      get the index.
  521.  
  522.   3. Convert the resulting device independent file `sipp.dvi' to a form
  523.      which your printer can output and print it.  If you have a
  524.      postscript printer there is a program, `dvi2ps', which can do
  525.      this.  There is also a program which comes together with TeX,
  526.      `dvips', which you can use.
  527.  
  528.  
  529. 
  530. File: sipp,  Node: Getting started,  Next: Basic concepts,  Prev: Installation,  Up: Top
  531.  
  532. Getting started
  533. ***************
  534.  
  535.    This chapter will be a small introduction of SIPP. We will go through
  536. the steps of creating a simple scene and then enhance it with some
  537. special effects. No specific details about the functions we use will be
  538. explained, they can be found in other parts of this manual.
  539.  
  540.    The first two things in a program using SIPP should be inclusion of
  541. `sipp.h' and a call to `sipp_init()'. Then we can start using the
  542. functions in SIPP to create a scene:
  543.  
  544.  
  545.      #include <stdio.h>
  546.      
  547.      #include <sipp.h>
  548.      #include <primitives.h>
  549.      
  550.      main()
  551.      {
  552.          FILE     *image_fd;
  553.      
  554.          Object   *sphere;
  555.          Surf_desc sphere_surface;
  556.      
  557.      
  558.          sipp_init();
  559.      
  560.          sphere_surface.ambient = 0.4;
  561.          sphere_surface.specular = 0.6;
  562.          sphere_surface.c3 = 0.1;
  563.          sphere_surface.color.red = 0.70; /* firebrick red */
  564.          sphere_surface.color.grn = 0.13;
  565.          sphere_surface.color.blu = 0.13;
  566.          sphere_surface.opacity.red = 1.0; /* Totally opaque */
  567.          sphere_surface.opacity.grn = 1.0;
  568.          sphere_surface.opacity.blu = 1.0;
  569.      
  570.          sphere = sipp_sphere(2.0, 40, &sphere_surface, basic_shader, WORLD);
  571.          object_add_subobj(sipp_world, sphere);
  572.      
  573.          lightsource_create(1.0, 1.0, 1.0,  1.0, 1.0, 1.0,  LIGHT_DIRECTION);
  574.      
  575.          camera_params(sipp_camera, 0.0, 10.0, 0.0,
  576.                        0.0, 0.0, 0.0,  0.0, 0.0, 1.0,  0.4);
  577.      
  578.          image_fd = fopen("ex1.ppm", "w");
  579.          render_image_file(400, 400, image_fd, PHONG, 1);
  580.      }
  581.  
  582.    If the program is stored in a file called `ex1.c' we can create an
  583. executable program with the following command line:
  584.  
  585.      cc -o ex1 ex1.c -lsipp -lm
  586.  
  587.    When run, the program will create a PPM-file containing a 400x400
  588. image of a red sphere lit by a single lightsource.
  589.  
  590.    In the program we are going through the following steps: First we
  591. initialize the library with a call to `sipp_init()'. Next we fill in a
  592. description of surface properties in the kind of structure used in
  593. SIPP's basic internal shader.  We then create a sphere that will be
  594. shaded with the basic shader using the previously defined surface
  595. properties and tell SIPP to install this sphere among the objects that
  596. should be considered when rendering. We create a lightsource and define
  597. where the camera is and where it is looking. Last we open a file and
  598. tell SIPP to render the scene into that file.
  599.  
  600. Enhancing the scene
  601. ===================
  602.  
  603.    A single red sphere is not a very exciting image so we will now
  604. enhance the image with some more interesting effects. We will put a
  605. wooden floor under the sphere and exchange the lightsource for a
  606. spotlight that will cast a shadow of the sphere onto the floor. The
  607. floor is created as a simple block and we use the wood shader supplied
  608. in the library. There will be rather high frequencies in the wood
  609. pattern so we will render the image with some oversampling to make it
  610. look better. The code looks like this:
  611.  
  612.      #include <stdio.h>
  613.      
  614.      #include <sipp.h>
  615.      #include <primitives.h>
  616.      #include <shaders.h>
  617.      
  618.      main()
  619.      {
  620.          FILE     *image_fd;
  621.      
  622.          Object   *sphere;
  623.          Object   *floor;
  624.          Surf_desc sphere_surface;
  625.          Wood_desc floor_surface;
  626.      
  627.      
  628.          sipp_init();
  629.          sipp_shadows(TRUE, 600);
  630.      
  631.          sphere_surface.ambient = 0.5;
  632.          sphere_surface.specular = 0.6;
  633.          sphere_surface.c3 = 0.1;
  634.          sphere_surface.color.red = 0.70; /* firebrick red */
  635.          sphere_surface.color.grn = 0.13;
  636.          sphere_surface.color.blu = 0.13;
  637.          sphere_surface.opacity.red = 1.0; /* Totally opaque */
  638.          sphere_surface.opacity.grn = 1.0;
  639.          sphere_surface.opacity.blu = 1.0;
  640.      
  641.          sphere = sipp_sphere(2.0, 40, &sphere_surface, basic_shader, WORLD);
  642.          object_add_subobj(sipp_world, sphere);
  643.      
  644.          floor_surface.ambient = 0.5;
  645.          floor_surface.specular = 0.0;
  646.          floor_surface.c3 = 0.99;
  647.          floor_surface.scale = 3.0;
  648.          floor_surface.base.red = 0.770; /* Very light brown */
  649.          floor_surface.base.grn = 0.568;
  650.          floor_surface.base.blu = 0.405;
  651.          floor_surface.ring.red = 0.468; /* Darker brown */
  652.          floor_surface.ring.grn = 0.296;
  653.          floor_surface.ring.blu = 0.156;
  654.      
  655.          floor = sipp_block(20.0, 20.0, 1.0, &floor_surface, wood_shader,
  656.                             WORLD);
  657.          object_move(floor, 0.0, 0.0, -2.5); /* Place it under the sphere */
  658.          object_add_subobj(sipp_world, floor);
  659.      
  660.          spotlight_create(10.0, 10.0, 10.0,  0.0, 0.0, 0.0,  40.0,
  661.                           1.0, 1.0, 1.0,  SPOT_SOFT,  TRUE);
  662.      
  663.          camera_params(sipp_camera, 0.0, 10.0, 0.0,
  664.                        0.0, 0.0, 0.0,  0.0, 0.0, 1.0,  0.4);
  665.      
  666.          image_fd = fopen("ex2.ppm", "w");
  667.          render_image_file(400, 400, image_fd, PHONG, 2);
  668.      }
  669.  
  670. 
  671. File: sipp,  Node: Basic concepts,  Next: Initializations,  Prev: Getting started,  Up: Top
  672.  
  673. Basic concepts
  674. **************
  675.  
  676.    This chapter introduces and briefly explains some of the basic
  677. concepts used in SIPP. They will later be used in this manual without
  678. further explanation.
  679.  
  680. * Menu:
  681.  
  682. * Polygons::            What kind of polygons are handled.
  683. * Surfaces::            What is a surface.
  684. * Objects::             What is an object.
  685. * Texture coordinates:: What is texture coordinates.
  686. * Shading functions::   What is a shading function.
  687. * Surface descriptions::What is a surface description.
  688. * Datatypes::           Datatypes defined by SIPP.
  689.  
  690. 
  691. File: sipp,  Node: Polygons,  Next: Surfaces,  Up: Basic concepts
  692.  
  693. Polygons
  694. ========
  695.  
  696.    SIPP can actually only render polygons, so everything else must be
  697. built from those. SIPP can handle planar polygons without holes, either
  698. convex or concave. The polygons have a defined front and back side, and
  699. which is which is defined by the order in which the polygon vertices are
  700. given.  Vertices must be given counterclockwise when looking at the
  701. front side of the polygon.
  702.  
  703. 
  704. File: sipp,  Node: Surfaces,  Next: Objects,  Prev: Polygons,  Up: Basic concepts
  705.  
  706. Surfaces
  707. ========
  708.  
  709.    Surfaces are the first step above polygons in the object hierarchy
  710. supported by SIPP. A surface is a collection of polygons that is shaded
  711. by the same shader (*Note Shading functions::) using the same surface
  712. description (*Note Surface descriptions::). A pointer to that shader and
  713. surface description is stored in the surface. If polygons within a
  714. surface share vertices, the surface normal will be interpolated across
  715. the polygons at rendering time, to create the impression of a smooth
  716. surface.
  717.  
  718. 
  719. File: sipp,  Node: Objects,  Next: Texture coordinates,  Prev: Surfaces,  Up: Basic concepts
  720.  
  721. Objects
  722. =======
  723.  
  724.    Objects are the highest level in the object hierarchy. An object is a
  725. collection of surfaces and/or other objects, which are then called
  726. subobjects. Object trees can be built to arbitrary depths.
  727. Transformations can be applied to objects and if an object has
  728. subobjects the transformation will propagate recursively down the object
  729. tree.  Every object has its current transformation relative to its
  730. parent object stored in a transformation matrix which can be read and
  731. written.
  732.  
  733.    There is a predefined object called `sipp_world'. When SIPP renders
  734. a scene it always starts in this object, so all objects that are to be
  735. rendered must be subobjects (or subsubobjects etc.) to it. The world
  736. object can be transformed like any other object.
  737.  
  738. 
  739. File: sipp,  Node: Texture coordinates,  Next: Shading functions,  Prev: Objects,  Up: Basic concepts
  740.  
  741. Texture coordinates
  742. ===================
  743.  
  744.    At each polygon vertex it is possible to specify up to three floating
  745. point numbers called texture coordinates. These numbers are linearly
  746. interpolated across the polygon and sent to the shader (*Note Shading
  747. functions::) at rendering time. It is up to the implementor of the
  748. shader to decide what to use them for. Texture coordinates are not
  749. affected by object transformations.
  750.  
  751. 
  752. File: sipp,  Node: Shading functions,  Next: Surface descriptions,  Prev: Texture coordinates,  Up: Basic concepts
  753.  
  754. Shading functions
  755. =================
  756.  
  757.    Every surface (*Note Surfaces::) in a scene has a shading function
  758. (or shader) associated with it. The shader is a regular C function,
  759. with a well defined interface, which is called for every pixel in the
  760. surface when it is rendered. SIPP supplies the shader with enough
  761. information for it to do a shading calculation, i.e. decide what color
  762. that particular pixel should have.  The shader is also responsible for
  763. deciding the opacity of the surface.  Besides the information supplied
  764. by SIPP (world position, lightsources, texture coordinates, etc.), the
  765. shader also gets a surface description (*Note Surface descriptions::)
  766. which the user has defined.
  767.  
  768. 
  769. File: sipp,  Node: Surface descriptions,  Next: Datatypes,  Prev: Shading functions,  Up: Basic concepts
  770.  
  771. Surface descriptions
  772. ====================
  773.  
  774.    Every surface (*Note Surfaces::) has a description of its surface
  775. properties. These properties can be e.g. color, material, opacity, etc.
  776. Exactly what information is stored depends on which shader (*Note
  777. Shading functions::) is used for shading the surface. The exact
  778. representation of this information is entirely up to the shader
  779. implementor.
  780.  
  781. 
  782. File: sipp,  Node: Datatypes,  Prev: Surface descriptions,  Up: Basic concepts
  783.  
  784. Datatypes
  785. =========
  786.  
  787.    The include file `sipp.h' defines several datatypes that are used
  788. when working with SIPP. We will describe them briefly here and also give
  789. the definitions for those that a user might need to access.
  790.  
  791.    * `bool'
  792.  
  793.      A boolean type which can have the value `TRUE' or `FALSE'.
  794.  
  795.    * `Object'
  796.  
  797.      This is an abstract data type holding information about an object.
  798.      Functions that creates objects returns pointers to `Object' and all
  799.      functions that operate on objects, e.g. transformations, take such
  800.      pointers as parameters.
  801.  
  802.    * `Surface'
  803.  
  804.      Similar to `Object' but contains information about a surface. The
  805.      user only needs to handle pointers to this type also.
  806.  
  807.    * `Color'
  808.  
  809.      This is a structure with three members describing a color in
  810.      RGB-space.  Each member is a double and should have a value in the
  811.      range [0, 1].
  812.           typedef struct {
  813.                   double   red;
  814.                   double   grn;
  815.                   double   blu;
  816.           } Color;
  817.  
  818.    * `Vector'
  819.  
  820.      Structure defining a 3-D vector. *Note Vector operations:: for more
  821.      detailed information.
  822.           typedef struct {
  823.                   double x;
  824.                   double y;
  825.                   double z;
  826.           } Vector;
  827.  
  828.    * `Transf_mat'
  829.  
  830.      A transformation matrix is used in every object to hold its current
  831.      transformation. The matrix is stored as a 4x3 matrix instead of a
  832.      complete 4x4 matrix in order to save space.  *Note Matrix
  833.      operations:: for more detailed information.
  834.           typedef struct {
  835.                   double   mat[4][3];
  836.           } Transf_mat;
  837.  
  838.    * `Camera'
  839.  
  840.      `Camera' is a structure holding a virtual camera. All functions
  841.      involved work with pointers to this type. SIPP provides a
  842.      predefined `Camera' and a pointer to it called `sipp_camera'. This
  843.      camera is the default viewpoint used when rendering a scene.
  844.  
  845.    * `Lightsource'
  846.  
  847.      This structure hold information about a lightsource. Two members
  848.      in the struct are of interest to users writing their own shaders.
  849.           Color         color;
  850.      and
  851.           Lightsource  *next;
  852.      `color' decides the color of the light emitted from the lightsource
  853.      and `next' points to the next lightsource defined in the scene (or
  854.      NULL). *Note Writing your own shaders:: for a description of how
  855.      to use this information.
  856.  
  857.    * `Surf_desc'
  858.  
  859.      This is the surface description (*Note Surface descriptions::) for
  860.      the internal shader, `basic_shader()' (see *Note The basic
  861.      shader::). It has the following definition:
  862.           typedef struct {
  863.                   double  ambient;
  864.                   double  specular;
  865.                   double  c3;
  866.                   Color   color;
  867.                   Color   opacity;
  868.           } Surf_desc;
  869.  
  870.         * `ambient' is a number in the range [0, 1] specifying how much
  871.           of the surface color that is visible when the object is not
  872.           lit by any lightsource.
  873.  
  874.         * `specular' is a number in the range [0, 1] specifying how much
  875.           light that is reflected in a specular highlight on the
  876.           surface.
  877.  
  878.         * `c3' is also a number in the range [0, 1]. It specifies how
  879.           "shiny" the surface is. 0 means a very shiny surface while 1
  880.           indicates a rather dull one.
  881.  
  882.         * `color' is simply the color of the surface.
  883.  
  884.         * `opacity' specifies how opaque the surface is. This is stored
  885.           as a color to allow different opacities for the different
  886.           color bands. The values should be in the range [0, 1] with 1
  887.           indicating a completely opaque object and 0 a completely
  888.           transparent (invisible) one.
  889.  
  890. 
  891. File: sipp,  Node: Initializations,  Next: Creating objects,  Prev: Basic concepts,  Up: Top
  892.  
  893. Initializations
  894. ***************
  895.  
  896.    Before using any of the functions, SIPP needs to be initialized.
  897. Initialization is done with a call to the following function:
  898.      void
  899.      sipp_init()
  900.    Apart from initializations, some default settings are created:
  901.    * Backfacing polygons are culled.
  902.  
  903.    * Background color is black.
  904.  
  905.    * No shadows are cast.
  906.  
  907.    * The camera is placed in (0 0 10), looking at the origin and with
  908.      the world y-axis as the up-axis.  `sipp_init()' takes no parameters
  909.  
  910.    There are also some functions that determine various global behavior
  911. of SIPP. These functions can be called at any time:
  912.      void
  913.      sipp_background(red, green, blue)
  914.              double  red;
  915.              double  green;
  916.              double  blue;
  917.    This function sets the background color in the rendered image. The
  918. parameters are doubles in the range [0, 1]. The default value (set by
  919. `sipp_init()') is black.
  920.  
  921.      void
  922.      sipp_show_backfaces(flag)
  923.              bool  flag;
  924.    Normally SIPP checks if a polygon is facing away from the viewpoint
  925. and if that is the case, the polygon is not considered in the rendering.
  926. There are times when this is not desirable. If one have a database of
  927. polygons with inconsistent orientations (see *Note Polygons::), it is
  928. necessary to render all polygons in it. There are also cases when
  929. objects have holes and backfacing polygons are visible through that
  930. hole. If `flag' is `TRUE' SIPP will render all polygons, if `flag' is
  931. `FALSE' (default), backfacing polygons will be culled.
  932.  
  933.      void
  934.      sipp_shadows(flag, size)
  935.              bool  flag;
  936.              int   size;
  937.    This function tells SIPP if it objects should cast shadows. When
  938. `flag' is `TRUE' shadows are cast. The default is not to do it. Only
  939. some types of lightsources are capable of producing shadows and it is
  940. possible to turn that ability on and off for each such lightsource
  941. (*Note Lights::). SIPP uses a technique called depth maps to do shadows
  942. (*Note Shadows::). It is a kind of texture mapping and the size of the
  943. depth maps are defined by the parameter `size'. As a rule of thumb one
  944. could say that the depth maps should be at least as large as the image
  945. itself but this may vary from case to case.
  946.  
  947.    A word of warning: Rendering images with shadows requires very large
  948. amounts of memory and takes considerably longer time than doing it
  949. without them.
  950.  
  951. 
  952. File: sipp,  Node: Creating objects,  Next: Transformations,  Prev: Initializations,  Up: Top
  953.  
  954. Creating objects
  955. ****************
  956.  
  957.    This chapter describes how to build SIPP objects from polygons and
  958. up.  In the library there are also a number of functions that create
  959. complete objects on a higher level (see *Note Object primitives::).
  960. Those functions all use the low level tools described here.
  961.  
  962. * Menu:
  963.  
  964. * Creating polygons and surfaces::      The lowest levels.
  965. * Building objects::                    Objects and hierarchies of them.
  966. * Duplicating objects::                 More instances of old objects.
  967.  
  968. 
  969. File: sipp,  Node: Creating polygons and surfaces,  Next: Building objects,  Up: Creating objects
  970.  
  971. Creating polygons and surfaces
  972. ==============================
  973.  
  974.    To build polygons and surfaces, SIPP uses two stacks, a vertex stack
  975. and a polygon stack. Polygons are created by pushing vertices onto the
  976. vertex stack and then calling a function that creates a polygon from
  977. these vertices and push this newly created polygon onto the polygon
  978. stack. When a number of polygons have been defined they can then be
  979. combined into a surface.
  980.  
  981.    The order in which vertices are pushed are important because this
  982. determines the front and the back face of the polygon. Vertices should
  983. be pushed in counterclockwise order when looking at the front face of
  984. the polygon.
  985.  
  986.    Note also that if polygons share vertices, these vertices should be
  987. pushed for each polygon. SIPP looks up shared vertices automagically.
  988.  
  989.    The following functions are used in the described process:
  990.  
  991.      void
  992.      vertex_push(x, y, z)
  993.              double  x, y, z;
  994.    Push a vertex onto the vertex stack.
  995.  
  996.      void
  997.      vertex_tx_push(x, y, z,  u, v, w)
  998.              double  x, y, z;
  999.              double  u, v, w;
  1000.    Push a vertex with texture coordinates defined by (u, v, w) onto the
  1001. vertex stack. Calls to `vertex_push()' and `vertex_tx_push()' should
  1002. not be mixed within a polygon since that would make texture
  1003. interpolation to produce garbage. `vertex_push()' gives the vertex
  1004. texture coordinates (0 0 0).
  1005.  
  1006.      void
  1007.      polygon_push()
  1008.    Takes all vertices currently on the vertex stack and creates a
  1009. polygon from them. The new polygon is pushed onto the polygon stack and
  1010. the vertex stack is emptied.
  1011.  
  1012.      Surface *
  1013.      surface_basic_create(ambient, red, green, blue, specular, c3,
  1014.                   opred, opgreen, opblue)
  1015.              double  ambient;
  1016.              double  red, green, blue;
  1017.              double  specular;
  1018.              double  c3;
  1019.          double  opred, opgreen, opblue;
  1020.    Takes all polygons currently on the polygon stack, creates a surface
  1021. from them and returns a pointer to the new surface. The created surface
  1022. will be shaded with the basic shading function `basic_shader()' and the
  1023. arguments to `surface_basic_create()' are the values that will be
  1024. placed in the surface description, which for `basic_shader()' is of
  1025. type `Surf_desc'(see *Note Basic concepts:: and *Note Shaders::).
  1026.  
  1027.      Surface *
  1028.      surface_create(surface_desc, shader)
  1029.              void    *surface_desc;
  1030.              Shader  *shader;
  1031.    Takes all polygons currently on the polygon stack, creates a surface
  1032. from them and returns a pointer to the new surface. The created surface
  1033. will be shaded with the shading function `shader' using the surface
  1034. description pointed to by `surface_desc' (see *Note Shaders::).
  1035.  
  1036.      void
  1037.      surface_basic_shader(surface, ambient, red, green, blue, specular, c3,
  1038.                   opred, opgreen, opblue)
  1039.              Surface *surface;
  1040.              double   ambient;
  1041.              double   red, green, blue;
  1042.              double   specular;
  1043.              double   c3;
  1044.              double   opred, opgreen, opblue;
  1045.    This function is used when a previously created surface should be
  1046. changed so that it is shaded with `basic_shader()'. This function can
  1047. also be used to set new values in the surface description if `surface'
  1048. is already shaded with `basic_shader()'.
  1049.  
  1050.      void
  1051.      surface_set_shader(surface, surface_desc, shader)
  1052.              Surface *surface;
  1053.              void    *surface_desc;
  1054.              Shader  *shader;
  1055. This function is used when a previously created surface should be
  1056. changed so that it is shaded with another shader than the one specified
  1057. at creation time.
  1058.  
  1059. 
  1060. File: sipp,  Node: Building objects,  Next: Duplicating objects,  Prev: Creating polygons and surfaces,  Up: Creating objects
  1061.  
  1062. Building objects
  1063. ================
  1064.  
  1065.    An object in SIPP is a more abstract concept than surfaces and
  1066. polygons.  It is a general "container" which can hold several surfaces
  1067. and also several other objects, which are then called subobjects. Such
  1068. hierarchies, or trees, of objects can be built to arbitrary depths. When
  1069. an object is transformed in some way, the transformation is propagated
  1070. down to all objects below it in the tree.
  1071.  
  1072.    When SIPP renders a scene it begins in the predefined object
  1073. `sipp_world' and recursively traverses the tree under it, rendering all
  1074. objects it finds. This means that it is perfectly possible to create
  1075. objects that will not be rendered. For an object to be rendered it must
  1076. be installed somewhere in the tree below `sipp_world'.
  1077.  
  1078.    To build objects and object trees the following functions are
  1079. provided:
  1080.  
  1081.      Object *
  1082.      object_create()
  1083.    This function creates a new object and returns a pointer to it. The
  1084. new object contains no surfaces or subobjects, and is not installed in
  1085. any tree.
  1086.  
  1087.      void
  1088.      object_delete(object)
  1089.              Object  *object;
  1090.    Delete an object. Release all memory occupied by an object, its
  1091. surfaces and its subobjects. This operation is only possible to do on a
  1092. top level object, i.e. an object that is not a subobject to any other
  1093. object.  SIPP keeps track of internal references, and if some parts of
  1094. the tree below `object' are referenced from other objects (see *Note
  1095. Duplicating objects::), those parts are not deleted. It is not possible
  1096. to delete `sipp_world'.
  1097.  
  1098.      void
  1099.      object_add_surface(object, surface)
  1100.              Object  *object;
  1101.              Surface *surface;
  1102.    Install a surface in an object.
  1103.  
  1104.      void
  1105.      object_sub_surface(object, surface)
  1106.              Object  *object;
  1107.              Surface *surface;
  1108.    Remove a surface from an object.
  1109.  
  1110.      void
  1111.      object_add_subobj(object, subobject)
  1112.              Object  *object;
  1113.              Object  *subobject;
  1114.    Install `subobject' as a subobject in `object'. Any transformations
  1115. of `subobject' will now be performed relative the local coordinate
  1116. system in `object'.
  1117.  
  1118.    A word of warning: There is no detection of "circular lists" in SIPP.
  1119. This means that if an object is installed as a subobject in an object
  1120. that is already below it in the tree, SIPP will go into eternal
  1121. recursion and crash when it tries to render the scene.
  1122.  
  1123.      void
  1124.      object_sub_subobj(object, subobject)
  1125.              Object  *object;
  1126.              Object  *subobject;
  1127.    Remove `subobject' as a subobject in `object'. If an object is to be
  1128. deleted, this function must be used first to remove it from its parent
  1129. object(s).
  1130.  
  1131. 
  1132. File: sipp,  Node: Duplicating objects,  Prev: Building objects,  Up: Creating objects
  1133.  
  1134. Duplicating objects
  1135. ===================
  1136.  
  1137.    If a complicated object has been built, it is often convenient to be
  1138. able to copy and reuse it. SIPP supports three levels of copying object
  1139. hierarchies:
  1140.  
  1141.      Object *
  1142.      object_instance(object)
  1143.              Object  *object;
  1144.    Create a new instance of an object and return a pointer to it. This
  1145. is the "shallowest" version of object copy in SIPP. It only creates a
  1146. copy of the top level object, pointed to by `object', and let the new
  1147. instance reference the same surfaces and subobjects as the original.
  1148. This saves space but has the property that if a subobject of one of the
  1149. instances are changed in some way (transformed, new subobjects, etc.)
  1150. the same change will appear in the other. The new object will have the
  1151. identity matrix as its transformation matrix.
  1152.  
  1153.      Object *
  1154.      object_dup(object)
  1155.              Object  *object;
  1156.    This version of object duplication copies not only the top level
  1157. object, but also all the subobjects recursively. All copied objects in
  1158. the tree will reference the same surfaces though, so even if object
  1159. changes will be unique in the two copies, surface changes (new color,
  1160. new shader, etc.) in one copy will affect both. The new object will
  1161. have the identity matrix as its transformation matrix.
  1162.  
  1163.      Object *
  1164.      object_deep_dup(object)
  1165.              Object  *object;
  1166.    Copy a complete object tree, objects, surfaces and all. The new
  1167. object will have the identity matrix as its transformation matrix.
  1168.  
  1169. 
  1170. File: sipp,  Node: Transformations,  Next: Lights,  Prev: Creating objects,  Up: Top
  1171.  
  1172. Transformations
  1173. ***************
  1174.  
  1175.    All objects can be transformed with the usual homogeneous
  1176. transformations: scaling, translation and rotation. The transformation
  1177. is stored in a transformation matrix for each object. This matrix can
  1178. also be read and written directly.
  1179.  
  1180.    The same transformations that can be applied to objects can also be
  1181. applied to the matrices directly.  There is also a vector type defined
  1182. and a number of operations defined on it.
  1183.  
  1184. * Menu:
  1185.  
  1186. * Geometric operations::        Vector and matrix operations.
  1187. * Object transformations::      Transformations of objects
  1188.  
  1189.